This file provides a more complete reference for LocalHelp users.
Installing LocalHelp
There is virtually no installation required for LocalHelp. If you wish to run the application from your hard disk, just drag the contents of the diskette into a folder on the hard disk.
TIP: Since LocalHelp needs no other installation, one recommended procedure is to keep LocalHelp on a floppy disk. This allows you to visit various locations connected to the network and run LocalHelp to monitor the network from that location.
Hardware Requirements
LocalHelp runs on the following Macintosh computers:
All members of the Macintosh II Family
Macintosh SE/30, SE
Macintosh LC, Classic, Classic II, Portable, Plus
Macintosh Powerbooks
Macintosh Quadras
Macintosh Centris'
You will need to be sure your LocalTalk hardware is installed before you can capture packets with LocalHelp.
Software
LocalHelp requires Macintosh System 6.0.5 or later and is fully-compatible with System 7.X. It also requires AppleTalk version 54 or greater.
Memory
LocalHelp is normally configured to use one megabyte of memory. However, it may be configured to run with more if you wish a larger capture buffer. The amount of memory you will want to assign to LocalHelp in this situation depends upon the number of packets you wish to capture and the RAM available on the Macintosh. To change the memory size allocated, select the LocalHelp icon from the Finder and choose the "Get Info…" command in the File menu. Change the value for Application Memory Size (K) to show the amount of memory you wish to give LocalHelp.
TIP: To use memory more efficiently, it may not be necessary to capture every packet to understand what is happening on your network. That is why LocalHelp provides capture filtering.
Compatibility
LocalHelp is compatible with almost all applications except other AppleTalk networking applications. Very often, AppleTalk network software will register itself as an AppleTalk client. LocalHelp must “unregister” all services to monitor the network.
Network Services
When you begin capturing packets with LocalHelp, the program will ask if it is okay to disconnect from these services by presenting a warning message. If you choose "Disconnect Services", LocalHelp will prevent the use of AppleTalk by any other network services, which means that the network software on your Macintosh will no longer function properly. You may prevent the disconnection from taking place by clicking on the "Cancel" button. After choosing Cancel, you can quit LocalHelp and disconnect these network services through their own normal termination sequence.
Filtering
If your network is very busy, you will quickly find that the number of packets LocalHelp captures in a short time can be quite large. Finding the packets in which you are interested can be difficult and time-consuming. For this reason, LocalHelp provides four types of filtering to eliminate the inconsequential or uninteresting packets from your packet capture.
Event Triggering
In addition to filtering, LocalHelp includes "Event Triggering", which allows you to set LocalHelp to begin capturing packets (or stop capturing packets) based on an event such as a certain time of day, receipt of a certain type of packet, or receipt of a packet from a particular device.
AppleTalk Addresses
AppleTalk network addresses are expressed as two integers separated by a period: a network number followed by a period followed by a node number. For example, 1000.93 is an AppleTalk address in which the network number is 1000 and the node number is 93. Every AppleTalk packet on LocalTalk contains a one-byte destination address and a one-byte source address as the first two bytes following the hardware preamble. These node addresses are referred to in LocalHelp as LLAP addresses, because they reflect the destination and source of the packet on the LocalTalk network to which LocalHelp is directly connected.
Error Packets
LocalHelp recognizes and can capture three different types of error packets:
CRC Error- A CRC (cyclic-redundancy check) Error occurs when the Frame Check Sequence (FCS) fails. As every byte is transmitted and received on the network, the byte is also used to determine a 16-bit checksum value from a polynomial equation. At the end of the packet, two additional bytes are transmitted which force the checksum to a known constant (0x1D0F). On the receiving end, for every byte received, if the checksum does not match the known constant, a CRC error is flagged, but it really doesn’t matter if it matches until after all bytes including the CRC bytes are received. Nearly all LocalTalk devices use hardware which automatically computes, generates and checks the correct CRC information without software computation. LocalHelp checks the status of the CRC flag in this hardware only after the packet is completely received. A CRC error often occurs because some other error has occurred. Also, if a packet is prematurely truncated or LocalHelp only sees the last part of a packet for some reason, it will detect the problem as a CRC error.
Overrun Error- An "Overrun" Error occurs when the receiving device is not able to read the bytes from the network fast enough, and the next byte of the packet arrives before the network software has read in the previous byte. This might be caused by the transmitting device sending bytes out faster than the network legally allows, or it might be caused by bytes being "fractured" because of cable noise or connection problems. However, the most likely reason for the occurrence of overrun errors is LocalHelp's inability to keep up with network traffic. Usually, this is because the volume of traffic is too large relative to the type, amount of memory and speed of the Macintosh on which LocalHelp is running. Overrun errors can also occur because of the activity of other programs which are running in parallel with LocalHelp in a multi-application environment.
Underrun Errors- An "Underrun" Error occurs when the transmitting node fails to transmit the next byte of a packet in the time frame required by the network hardware. This might appear to happen if the byte is "lost" due to noise or cable connection problems, or if software on the transmitting device is not able to keep up with "feeding" bytes to the transmitting hardware.
Creating and Editing Filters
There are two ways to open the Filter Settings window, where filters are defined. You can double-click a filter name in the Filters window which will open the Filters Settings window, showing the settings for the selected filter or use the "Filters" menu, which EtherHelp adds to its menu bar when "Filtering..." is selected in the Capture menu. Instead of clicking in the box that precedes a filter's name, you can use the Filters menu to enable or disable a selected filter by choosing Add... in the Filters menu to open the Filters Settings window with no existing settings or name. When you open the Filter Settings window by choosing Add..., you will see an "Add More..." button between the OK and Cancel buttons. When you click "Add More...", the current filter is added to the list and all information is retained in the Filter Settings window. This is useful if you want to create additional filters with similar specifications.
Each filter can have up to 4 attributes, each of which can be enabled or disabled in a filter:
• Address attributes test each packet's source or destination address (or both). Address filtering is used to capture or ignore packets to or from particular devices.
• Protocol attributes test the protocol type in a packet. Protocol filtering is used to capture or ignore packets of a specified protocol type, such as AppleTalk, DECnet, Ethernet, etc.
• Offset attributes test specific bytes or bits in each packet for a user-defined value. Offset filtering is used to specify exactly which packets you want to capture or ignore.
• Error attributes test for particular error conditions in packets.
Address Filtering
By using Address Filtering, you may filter packets according to the addresses they contain. You may want to instruct LocalHelp to capture only packets that originate from a certain address, packets destined for a particular address or packets travelling between a particular pair of machines. Moreover, using LocalHelp’s ability to capture packets based upon embedded AppleTalk internet addresses, you may monitor packets on your network destined to and from machines on remote networks. If your network contains a link to other networks, you may monitor the network activity through the link by having LocalHelp show you only packets with the LLAP source and destination addresses containing the link device’s address.
When To Use Address Filters
Address filtering is very useful for focusing on packets between specific network devices. Using LocalHelp's ability to capture packets based upon embedded logical addresses, you may even monitor packets on your network sent to and received from machines on remote networks. If your network contains a link to other networks, you can monitor the network activity through the link by using an address filter to capture only packets containing the link device's address.
Using "Wild Cards" To Specify a Range of Addresses
You can use the asterisk (*) character as a "wild card" in specifying physical or logical addresses. The (*) character matches any number in the field in which it appears. For example, to match any node on the AppleTalk network "2000", you can specify the network number followed by an (*) in the node number field: "2000.* Or, to specify the AppleTalk broadcast address on any AppleTalk network, you can use an(*) in the network number portion of the address: "*.255".
Capturing All Packets From One Device
This example creates a filter that can be used to capture or ignore all packets being transmitted from a particular AppleTalk node:
1. Select "Filtering..." from the Capture menu.
2. Select "Add..." from the Filters menu and the Filters Settings window will open.
3. Type a name (up to 23 characters) in the Filter: edit field at the top of the window.
4. Click the Address Filter check box.
5. Choose an address type from the Type pop-up menu. In this example, choose AppleTalk.
6. Click the Address-1 edit field, and enter a logical AppleTalk node address in that field.
NOTE: The node address you specify must be consistent with the address type you selected in the Type menu. If you had selected Ethernet instead of AppleTalk, you would need to enter the device's physical address.
7. Click next to "Any Address" in the Address-2 box.
8. Click next to "From Address-1 to Address-2". When you click in a "From Address..." check box, an arrow appears in the middle of the address filters area, to indicate the direction of the filter. Clicking on this arrow cycles through the possible directions (source, destination, or both) and is a shortcut for clicking the From Address... boxes.
To capture packets that are destined for a specific device, click next to "From Address-2 to Address-1" instead. You should see a left-pointing arrow appear in the middle of the address filter area. To capture packets sent to and received from a device to monitor traffic in and out of a specific address, click next to "From Address-2 to Address-1" and next to "From Address-1 to Address-2". A bidirectional arrow appears.
To monitor traffic in either direction (or in both directions) between two devices, turn off the "Any Address" button in the Address-2 box and enter the second specific address in the Address-2 field. Then click both check boxes: "From Address-1 to Address-2" and "From Address-2 to Address-1".
Protocol Filters
Protocol filtering allows you to capture only packets of a certain protocol type. For example, if a Mac is unable to "see" an AppleShare server on LocalTalk, you might want to focus on NBP packets, open the Chooser or Silver Cloud window and select the server again.
Creating Protocol Filters
There are two ways to specify a protocol type in a filter: by protocol name or by the number that represents the LLAP or DDP type. The following example creates a filter that can be used to capture or ignore all NBP packets:
1. Select "Filtering..." from the Capture menu.
2. Select "Add..." from the Filters menu.
3. Type a name in the Filter: edit field.
4. Click the Protocol Filter check box.
5. Choose the DDP Protocol specification from the protocol "Type" pop-up menu.
6. Type the DDP type identifier in the text entry field. In this case, NBP is DDP type 2, so type "2" in the protocol text entry field.
7. Click OK and close the window, or click Add More... if you wish to define additional filters.
Offset Filters
For most uses of LocalHelp, address and DDP filtering are sufficient to specify the network activity you wish to view. Sometimes, however, you may wish to capture a packet only if it meets very specific criteria. For example, you may want to capture only NBP Broadcast Request packets. To do so, you must first know that NBP Broadcast Request packets have an NBP function field of "1". You can find this type of internal packet format information in "Inside AppleTalk, Second Edition". You can then use offset filtering to instruct LocalHelp to examine the exact location within a packet where such information is stored and to capture only those packets that match your criteria. An offset is the byte number where certain information or data occurs in a packet.
Each offset filter can test up to 16 bytes in a packet for a specified value at each location. If all of the "active" tests in a filter pass (and the filter is enabled), the packet is captured.
NOTE: Use offset filters with an address filter to fine-tune the packets you wish to view. For example, you can use an addess filter to specify a particular AppleTalk router, and then set an offset filter that specifies the standard offset for NBP-Long packets with a further offset limiting packet capture to only those packets being routed into a particular network. With offset filters, you can specify completely the exact packets you wish to view.
Offset Filters At Work
This section describes the "test" values you can enter in the Offset Filter window to pinpoint the byte and which bits within that byte you want to use in the filter. To open the Offset Filter window, follow these steps:
1. Select Filtering... form the Capture menu.
2. Select Add... from the Filters menu.
3. Click the Offset Filter button to open the Offset Filter window. In this window, there are 16 rows, each of which can be used to specify a test for one location in a packet. Each row has four fields and an enable switch. The four fields are as follows:
• Name - The text in this field (up to 23 characters) is optional and does not affect the filtering of packets. It is used to help you remeber the meaning of the specified values.
• Offset - The number in this field indicates the location of a byte in the packet. If you enter 0, the first byte of a packet will be examined, 1 causes LocalHelp to examine the second byte and so forth. You can enter the number in hex ($0 to $FF) or decimal (0-255). However, the number is always stored in decimal.
• Mask - The number in this field is used to isolate the bits inside of the byte specified by the Offset field. This value is AND'ed with the value present in the byte and the result is examined. If you enter $FF, LocalHelp examines all of the bits in the byte, while a mask of 80 causes LocalHelp to examine only the most significant bit.
• Value - The number in this field is the "constant" that LocalHelp compares to the value it obtains by applying the Mask to the Offset byte. If the value specified here matches the value in the specified byte (or bits) in a packet, the test passes.
Creating An Example Offset Filter
This example creates an offset filter to capture AppleTalk packets of a specific datagram length. To create the filter, you must first know that the "datagram length" field in AppleTalk packets is a 10-bit field that begins in the 22nd byte of a packet with the 2 least significant bits and continues as the eight bits in the following byte. So, this filter will need to include tests for both the 22nd and 23rd byte of each packet. This type of information can be found in "Inside AppleTalk, Second Edition".
Say that you want to capture all AppleTalk packets with a datagram length of 420 (0x1A4). The total value to test for is 420 (0x1A4). First, make sure that existing filters will not prevent these packets from being captured; in fact, you might want to limit capture to just AppleTalk packets. Then, follow these steps:
1. Select "Filtering..." from the Capture menu.
2. Select "Add..." from the Filters menu.
3. Assign a name to the filter, e.g., "DDP Long".
4. Click the Offset Filters button to open the Offset Filter window.
5. Click the first check box to enable this test, and then type a name in the Name field to remind you of the function of this test; e.g.: "DDP len-hi".
6. Specify the byte you want to examine, in this case byte 22, by typing a hex value in the Offset field: "0x15". Hex 15 is decimal 21, which represents the 22nd byte of the packet.
7. Specify the bits within this byte, in this case the 2 least significant bits, by typing a hex value in the Mask field: "0x3".
8. Specify the constant value "1" in the Value field: 0x1. The total value to test for is 420 (0x1A4), so the value for byte 22 should be 1.
9. Click the second check box to enable this test, and then type a name in the Name field to remind you of the function of this test, e.g.: "DDP len-low".
10. Specify the byte you want to examine, in this case byte 23, by typing a hex value in the Offset field: "0x16". Hex 16 is decimal 22, which represents the 23rd byte of the packet.
11. Specify the bits within this byte, in this case all eight bits, by typing a hex value in the Mask field: "0xff".
12. Specify the constant value "A4" in the Value field: "Oxa4". The total value to test for is 420 (Ox1A4), so the value for byte 23 should be A4.
13. Click OK.
14. In the Filter Settings window, click the Offset Filter box to enable this filter.
15. Type a name in the Filter: edit field at the top of the window.
16. Click OK to exit, or click "Add More..." if you want to create new filters.
Error filters
Error filtering allows you to capture or ignore packets that contain errors.
Triggering
You may wish to keep LocalHelp idle (not capturing) or in a holding pattern (continuously capturing) until a specific event occurs on your network. These events can be one or more of the following:
• an address or DDP type appears in a packet on the network.
• a user-defined value in some bits or bytes appears in a packet on the network.
• an error packet is received.
• the Macintosh system clock reaches a user-defined time.
When one of these events occur, LocalHelp can begin capturing packets. The automatic start of data capture based on network events is called Triggering.
Trigger Start
To configure LocalHelp to recognize a trigger event, you must specify the trigger parameters and then use a check box to indicate if the trigger is enabled or disabled. Each enabled trigger event is independent of the others, i.e., capture is started if any of the enabled trigger events occur.
• The “Time” event causes packet capture to start at a specified time.
• The "Filter" event causes packet capture to start when a specified filter is passed.
• The “Start Capture” check box is used to specify that capture of all packets, according to the filters, should begin when any of the trigger event conditions is met.
• The “Notify” check box is used to cause an audible alarm to sound at the occurrence of the trigger event.
Note: If the “Start Capture” check box is not checked, but the “Notify” check box is checked, only packets which cause the trigger event will be captured.
When Start Triggering is enabled, a small diamond appears next to the "Start Trigger..." item in the Capture menu and the "Start Capture" button turns into a "Start Trigger" button. By clicking on this button, or by using the "Start Trigger" item in the Capture menu, LocalHelp begins reviewing but NOT capturing packets until the trigger criteria is met.
Once clicked, LocalHelp will begin monitoring packets on the network and will continue to do so until one of the packets matches an enabled trigger criteria. If the “Notify” check box is checked, and the “Start Capture” check box is not checked, the packet causing the trigger will be captured, and LocalHelp will continue waiting for more trigger matches.
After triggering is activated, the button will be renamed to Abort Trigger. When the trigger event occurs, capture begins and the button reverts to its normal label of Stop Capture.
Saving and Restoring Settings
The settings file contains all the information required to set up filters and triggers. After you have set up your filters and triggers, LocalHelp will remember the settings each time it starts up. However, you can also save these settings to a separate file so that they can be selectively restored as required. In fact, you may have received a LocalHelp settings file from your vendor in order to streamline capture and subsequent diagnosis. A settings file is useful when different configurations of settings are repeatedly used for things like diagnostics and testing. To save and restore configuration settings, use the "Save Settings" and "Load Settings..." items from the File menu. Load Settings uses the Macintosh standard for opening files. The Save Settings Window is identical to the Macintosh standard for saving files.
The AG Group, Inc. specializes in easy-to-use software tools for troubleshooting, optimizing, maintaining and expanding multivendor computer networks. While designed to take advantage of the intuitive, graphical interface of the Macintosh, our products can be used in virtually any heterogeneous networking environment.
If you are intrigued by LocalHelp and would like to learn more about our other network management tools, please contact us using one of the following methods:
Phone number: (510) 937-7900
Fax number: (510) 937-2479
Mailing address: 2540 Camino Diablo, Suite 202, Walnut Creek, CA 94596
